/*
 *  Class name: PlayerServiceBeanLocal.java
 *  Version: 1.0
 *  Date: 30.10.2013
 */
package cz.muni.fi.pa165.soccergamesarchive.businesslayer.services;

import cz.muni.fi.pa165.soccergamesarchive.businesslayer.dtos.PlayerDTO;
import cz.muni.fi.pa165.soccergamesarchive.businesslayer.dtos.PlayerDetailDTO;
import java.util.List;
import java.util.Map;
import javax.ejb.Local;

/**
 *
 * @author Michal Ďuriš
 */
@Local
public interface PlayerServiceBeanLocal {

    /**
     * Store new player to database
     *
     * @param player player to be stored
     *
     * @return successfully database stored player
     *
     * @throws IllegalArgumentException if player dont exist or has incorrect
     *                                  record
     */
    public PlayerDTO addPlayer(PlayerDTO player) throws RuntimeException;

    /**
     * Update/change existing player record in database
     *
     * @param player player, which record has to be updated
     *
     * @return player with updated record (entity in managed state)
     *
     * @throws IllegalArgumentException if player dont exist, hasnt id or has
     *                                  incorrect record
     */
    public PlayerDTO changePlayer(PlayerDTO player) throws RuntimeException;

    /**
     * Find players by specified first name, last name or full name
     *
     * @param firstName players first name to be searched
     * @param lastName  players last name to be searched
     *
     * @return list of found players
     *
     * @throws IllegalArgumentException if first and last name wasnt specified
     */
    public List<PlayerDTO> findPlayer(String firstName, String lastName) throws
            RuntimeException;

    /**
     * Retrieve all database stored players
     *
     * @return list of all players
     */
    public List<PlayerDTO> getAllPlayers() throws RuntimeException;

    /**
     * Retrieve limited number of stored players. Limit borders are determined
     * by parametres
     *
     * @param offset    index of first record
     * @param limit     number of retrieved records
     * @param filterMap filter policy for current data retrieval
     * @param orderMap  order policy for current data retrieval
     *
     * @return list of players in the specified interval with applied policies
     *
     * @throws IllegalArgumentException if offset or limit has incorrect value
     */
    public List<PlayerDTO> getLimitedNumberOfPlayers(int offset, int limit,
                                                     Map<String, Object> filterMap,
                                                     Map<String, Boolean> orderMap)
            throws RuntimeException;

    /**
     * Retrieve player from database by specified id
     *
     * @param id id of player to be retrieved
     *
     * @return player with specified id or null if player wasnt found
     *
     * @throws IllegalArgumentException if id has incorrect value
     */
    public PlayerDTO getPlayerById(Long id) throws RuntimeException;

    /**
     * Retrieve player detail from database by specified id
     *
     * @param id id of player to be retrieved
     *
     * @return player detail with specified id or null if player wasnt found
     *
     * @throws IllegalArgumentException if id has incorrect value
     */
    public PlayerDetailDTO getPlayerDetail(Long id) throws RuntimeException;

    /**
     * Method apply the filter policy to all players and then return a number of
     * corresponding players
     *
     * @param filterMap filter policy for current action
     *
     * @return count of players corresponding to the current filter policy
     *
     * @throws RuntimeException not possible to execute this action
     */
    public int getFilteredPlayersCount(Map<String, Object> filterMap) throws
            RuntimeException;

    /**
     * Delete existing player from database
     *
     * @param player player to be deleted
     *
     * @throws IllegalArgumentException if player dont exist or hasnt id
     */
    public void removePlayer(PlayerDTO player) throws RuntimeException;

}
